DOC: clarify add_reference_channels usage (Takeover #13664)#13846
DOC: clarify add_reference_channels usage (Takeover #13664)#13846Dpereaptkhamur-13 wants to merge 10 commits intomne-tools:mainfrom
Conversation
Dpereaptkhamur-13
requested review from
agramfort,
drammock,
larsoner and
mscheltienne
as code owners
|
Hey @Dpereaptkhamur-13 , I believe you don't have an account on circle ci that's why those checks are failing , login into your account & those tests will pass ! |
|
Hi @HansujaB, thank you for the tip! I have now logged into CircleCI and authorized the account. The tests should be ready to run once a maintainer approves the workflow. Thanks again for the help! |
|
Hi @Dpereaptkhamur-13, thanks for opening the PR. Right now, the message has been added to Rather, the note should be included in Just make sure if you use this text to action the suggested changes: https://github.com/mne-tools/mne-python/pull/13664/changes#r2892847499 and https://github.com/mne-tools/mne-python/pull/13664/changes#r2892851172 Then, it would be good to also add a note to the |
|
Hi @tsbinns, thank you for the detailed feedback! That makes complete sense—moving the clarification to set_eeg_reference and the tutorials ensures it's visible to users regardless of which function they check first. I will update mne/utils/docs.py and the preprocessing tutorial file accordingly. I'll ping you again once the changes are pushed! |
| .. note:: | ||
| If you wish to add a new reference channel (e.g., a mastoid) | ||
| to the data, use :func:`mne.add_reference_channels` | ||
| **before** calling this function. |
There was a problem hiding this comment.
I'd suggest specifically mentioning average referencing for sensor-space analyses. E.g.:
When performing average referencing in sensor-space analyses and the original reference electrode is not present as a zero-filled channel, this must first be added using :func:
~mne.add_reference_channelsbefore calling :func:~mne.set_eeg_referenceto avoid biasing the reference.
Also, please add a citation for the paper where this gets discussed (10.3389/frsip.2023.1064138). Have a look at :footcite: and :footbibliography: for examples of doing this after adding the citation to our BibTeX file.
There was a problem hiding this comment.
Hi @drammock, I've updated the documentation note with the sensor-space details and added the citation to references.bib as requested. I also included the footbibliography in the tutorial. Ready for another look!
|
|
||
| # .. note:: | ||
| # If you wish to add a new reference channel (e.g., a mastoid) | ||
| # to the data, use :func:`mne.add_reference_channels` | ||
| # **before** calling this function. |
There was a problem hiding this comment.
Please make this comment a bit more detailed, like in the previous PR: https://github.com/Farzah11/mne-python/blob/a8e92a3a7d8a83a021d81da9c6b1b38f678ad53f/tutorials/preprocessing/55_setting_eeg_reference.py#L144-L150
|
|
||
| note:: If you are adding a new reference channel to data that | ||
| will eventually be used with an average reference, | ||
| you should also call :meth:`mne.io.Raw.set_eeg_reference` | ||
| (or the equivalent Epochs/Evoked method) to ensure the | ||
| mathematical reference is updated correctly. |
There was a problem hiding this comment.
This information isn't so relevant to add_reference_channels. The purpose of this function isn't to change the reference, it just adds zero-filled channels.
3 participants
Reference issue (if any)
What does this implement/fix?
This PR completes the documentation clarification for add_reference_channels originally started in #13664. It addresses the mathematical requirements for average referencing in the docstrings, as requested in issue #13618.
Changes include:
Additional information